home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 051-075 / scopedisk63 / simreq / specs < prev   
Text File  |  1995-03-19  |  6KB  |  169 lines
  1. SimpleRequest
  2.  
  3. NAME
  4.     SimpleRequest -- Create and display a requester
  5.  
  6. SYNOPSIS
  7.  
  8.     SimpleRequest(Hailing_Text, Gadgets_Text, Window, Flags)
  9.  
  10. FUNCTION
  11.  
  12.     SimpleRequest will take the parameters fed it by the user,
  13.     and use them to create and display a 'Requester' (Actually,
  14.     just a window with some rendering and some gagdets in it).
  15.  
  16.     The Hailing_Text may be of any length, as may the Gadgets_Text.
  17.     The vertical bar character is used as a separator to 
  18.     delimit the gadgets, and the lines of the requester.
  19.     
  20.     The Window is the window (and derived Screen) to place the
  21.     requester into, and to use the font from.
  22.  
  23.     The Flags are:  
  24.  
  25.          SR_NOCENTERWINDOW - This will put the Requester Window
  26.                  at the top left corner of the screen,
  27.                  rather than centering it.
  28.  
  29.          SR_NOCENTERTEXT   - This will Left Justify the text in the
  30.                  requester, rather than centering it.
  31.  
  32.          SR_NODRAG         - Eliminate the drag bar that normally
  33.                  appears on requesters.  This is useful
  34.                      if you are doing a requester in a window
  35.                  with no title, (and in other cases).
  36.  
  37. INPUTS
  38.  
  39.     Hailing_Text - Pointer to a null-terminated string containing
  40.                 the text to be displayed in the requester.  The vertical 
  41.                bar character will act as a carriage return.
  42.  
  43.     Gadgets_Text - Pointer to a null-terminated string containing
  44.                the labels for the gadgets in this requester.
  45.                The vertical bar separates gadgets.  (See the sample)
  46.  
  47.     Window         - Pointer to the window that the requester is 
  48.                emanating from.  The text attributes of that
  49.                        window will be used to form the text in the 
  50.                requester.
  51.  
  52. RESULT
  53.  
  54.     An integer from 0 to however many gadgets you specified, in order
  55.       that they were specified.
  56.  
  57. SAMPLE
  58.  
  59.     SimpleRequest("Please insert volume|Workbench|in any drive",
  60.         "Retry|Cancel", SourceWindow, SR_NOCENTERTEXT|SR_NOCENTERWINDOW)
  61.  
  62.        - This will duplicate a system requester asking for a disk
  63.              named "Workbench".  It will look different, of course.
  64.  
  65.     SimpleRequest("Quit|Are you sure?", "Yes|No", Window, 0);
  66.  
  67.        - This is the kind of usage that SimpleRequest is designed
  68.          for.  You want an answer from the user - Quit, is it okay
  69.          with you? - which can be added using a single line of code.
  70.  
  71.     SimpleRequest("Operation Aborted", "Okay", Window, 0);
  72.  
  73.        - Yet another common type of requester.  A single line of
  74.          text informing the user that his operation has been
  75.          aborted, and a gadget for him to click on, "Okay".
  76.  
  77.  
  78.  
  79. DISCUSSION
  80.  
  81. SimpleRequest() is my first attempt at providing some additional
  82. functionality to the Intuition programmer.  Most programmers who
  83. do anything with Intuition on the Amiga either have to pick up a
  84. copy of one of the commercial Window-design aids, or waste a lot 
  85. of time either laying out requesters and such, or designing
  86. routines much like this one to do the work for them.
  87.  
  88. What It Does:
  89.  
  90. SimpleRequest starts by finding the longest line in your list of
  91. lines supplied for the text of the requester.  The width of the
  92. requester is based on this.
  93.  
  94. It next determines how long the gadgets would be if they were laid
  95. out across the bottom of the requester horizontally.  If this is
  96. less than the width of the screen, then we do it this way, otherwise
  97. we try stacking the gadgets on top of each other.
  98.  
  99. Note that all gadgets will be the same width and the same height - 
  100. it looks better this way.  The gadgets will be equally spaced across
  101. the bottom of the window if they are horizontal, or in a straight
  102. vertical line otherwise.
  103.  
  104. Here's the hard part:  SimpleRequest bases all it's calculations
  105. on the font supplied in the RastPort belonging to the Window which is
  106. supplied as an argument.  SimpleRequest will look "right" no matter
  107. how big or small (or mono-spaced or proportionally spaced) your font
  108. is.  This in itself makes it worth using SimpleRequest over the
  109. current System functions.
  110.  
  111. Other advantages that SimpleRequest provides: 
  112.  
  113.     - It allows any number of gadgets on the requester.  
  114.       The gadgets will be spaced such that they sit as nicely as
  115.       possible at the bottom of the requester (either stacked,
  116.       or in a vertical line).
  117.  
  118.     - It is much faster than an AutoRequest() - because it uses
  119.       a smart_refresh window, and doesn't use a Requester - 
  120.       just a window with some rendering and some gadgets in it.
  121.          It will take less chip ram, and move quicker, than a system
  122.       request.
  123.  
  124.     - SimpleRequest will use whatever font you are using in your
  125.       own window, automatically, and correctly.
  126.  
  127.     - It looks nicer.
  128.  
  129. Once the requester is up, it will wait for one of the gadgets to
  130. be hit, and return a value representing what order that gadget
  131. was supplied in (ie, for "YES|NO", Yes==0, No==1).
  132.  
  133. Possible Extensions:
  134.  
  135. As I said, this is my first draft.  I present it here to get input
  136. on what this needs - as it is a linkable object currently, whatever
  137. gets added here ultimately gets added to the size of any code using
  138. it.  There are a number of things it could use, though:
  139.  
  140.     - The requester should take Keyboard Input.  Maybe function
  141.       keys from F1, F2, F3, etc for each gadget in order of
  142.       appearance?  The first letter of the gadget?  Return?
  143.       Escape?
  144.  
  145.     - For simple "OK" requesters, a flag to tell the requester to
  146.       go away by itself after a certain period of time?
  147.       Fixed period or user-specifyable?
  148.  
  149.     - Should the requester make any attempt at blocking input
  150.       to the calling window?  Should this be left up to the
  151.       caller, or should it be a flag?
  152.  
  153.     - Should the rendering be different in Interlace?
  154.  
  155.     - How about getting strings?  Maybe a flag to indicate
  156.       that we want a String gadget on there?
  157.  
  158. How about other functions?  A library of this sort of function would
  159. make for a more "standard" user interface, (to the extent that
  160. AutoRequest does now), and would certainly make life easier for
  161. people using Intuition.
  162.  
  163. Thanks for listening - Feedback?
  164.  
  165.     Steve Tibbett
  166.     Bix: s.tibbett
  167.     Plink: STEVEX
  168.  
  169.